 (September 1999)(Disk 2).iso/Technical Publications/quicktime/qtdevdocs/images/qtsmban.gif){kind=small}
 (September 1999)(Disk 2).iso/Technical Publications/quicktime/qtdevdocs/images/qt4api.gif)
QuickTime 4 Reference
| Previous | Chapter Contents | Chapter Top | Next |
As with reading movie data, data handlers provide two distinct write facilities. The DataHPutData function is a simple synchronous interface that allows applications to append data to the end of a container.
The DataHWrite function is a more capable, asynchronous write function that is suitable for movie capture operations. As is the case with the DataHScheduleData function, your component calls the application's data-handler completion function when you are done with the write request.
There are several other helper functions that allow applications to prepare your data handler for a movie capture operation. The DataHCreateFile function asks your component to create a new container. The DataHSetFileSize and DataHGetFileSize functions work with a container's size, in bytes. The DataHGetFreeSpace function allows applications to determine when to make a container larger. The DataHPreextend function asks your component to make a container larger. Applications may call your component's DataHGetPreferredBlockSize function in order to determine how best to interact with your data handler.
Before writing data to a data reference, applications must call your component's DataHOpenForWrite function to open a write path to the container. The DataHCloseForWrite function closes that write path.
Note that some data handlers may not support write operations. For example, some shared devices, such as a CD-ROM "jukebox," may be read-only devices. As a result, it is very important that your data handler correctly report its write capabilities to client programs. See "Selecting a Data Handler" for information about the functions that client programs use to interrogate your data handler. For more information on writing movie data, see "Storing Movie Data" .
Your component opens its current data reference for write-only access.
pascal ComponentResult DataHOpenForWrite (DataHandler dh);
After setting your component's current data reference by calling the DataHSetDataRef function, client programs call the DataHOpenForWrite function in order to start writing to the data reference. Your component should open the data reference for write-only access. If the data reference is already open or cannot be opened, return an appropriate error code.
Your component closes write-only access to its data reference.
pascal ComponentResult DataHCloseForWrite (DataHandler dh);
Your component writes data to its current data reference. This is a synchronous write operation that appends data to the end of the current data reference.
pascal ComponentResult DataHPutData (
DataHandler dh,
Handle h,
long hOffset,
long *offset,
long size);
The DataHPutData function provides a high-level write interface. This is a synchronous write operation that only appends data to the end of the current data reference. That is, the client program's execution is blocked until your component returns control from this function, and the client cannot control where the data is written. As a result, most movie-capture clients (for example, Apple's sequence grabber component) use the DataHWrite function to write data when creating movies.
Your component writes data to its current data reference. This can be a synchronous write operation or an asynchronous operation, and can write data to any location in the container.
pascal ComponentResult DataHWrite (
DataHandler dh,
Ptr data,
long offset,
long size,
DHCompletionUPP completion,
long refCon);
The DataHWrite function provides both a synchronous and an asynchronous write interface. Synchronous write operations work like the DataHPutData function--the data handler component returns control to the client program only after it has serviced the write request. Asynchronous write operations allow client programs to queue write requests. Your data handler queues the request and immediately returns control to the calling program. After your component actually writes the data, it calls the client program's data-handler completion function.
Your component sets the size, in bytes, of the current data reference.
pascal ComponentResult DataHSetFileSize (
DataHandler dh,
long fileSize);
The DataHSetFileSize function is functionally equivalent to the File Manager's SetEOF function. If the client program specifies a new size that is greater than the current size, your component should extend the container to accommodate that new size. If the client program specifies a container size of 0, your component should free all of the space occupied by the container.
Your component returns the size, in bytes, of the current data reference.
pascal ComponentResult DataHGetFileSize (
DataHandler dh,
long *fileSize);
Your component creates a new container that meets the specifications of the current data reference.
pascal ComponentResult DataHCreateFile (
DataHandler dh,
OSType creator,
Boolean deleteExisting);
The DataHGetPreferredBlockSize function allows your component to report the block size that it prefers to use when accessing the current data reference.
pascal ComponentResult DataHGetPreferredBlockSize (
DataHandler dh,
long *blockSize);
Different devices use different file system block sizes. This function allows your component to report its preferred block size to the client program. Note that the client program is not required to use this block size when making requests. Some clients may, however, try to accommodate your component's preference.
Your component reports the number of bytes available on the device that contains the current data reference.
pascal ComponentResult DataHGetFreeSpace (
DataHandler dh,
unsigned long *freeSize);
Your component allocates new space for the current data reference, enlarging the container.
pascal ComponentResult DataHPreextend (
DataHandler dh,
unsigned long maxToAdd,
unsigned long *spaceAdded);
This function is essentially analogous to the File Manager's PBAllocContig function. Your component should allocate contiguous free space. If there is not sufficient contiguous free space to satisfy the request, your component should return a dskFulErr error code.
Client programs use this function in order to avoid incurring any space-allocation delay when capturing movie data.
| Previous | Chapter Contents | Chapter Top | Next |